\documentclass[12pt]{article}
\usepackage{psfig}
\usepackage{fullpage}

% bold math italic font
\newcommand{\mbf}[1]{\mbox{\boldmath $#1$}}

% symbol used for sqrt(-1)
\newcommand{\Ci}{\ensuremath{i}}

\newcommand{\var}{{\rm var}}
\newcommand{\trace}{{\rm tr}}

\newcommand{\Rotation}{{\bf R}}
\newcommand{\Boost}{{\bf B}}

\newcommand{\vRotation}[1][n]{\ensuremath{\Rotation_{\mbfs{\hat #1}}}}
\newcommand{\vBoost}[1][m]{\ensuremath{\Boost_{\mbfs{\hat #1}}}}

\newcommand{\rotat}{\ensuremath{\vRotation(\phi)}}
\newcommand{\boost}{\ensuremath{\vBoost(\beta)}}

\newcommand{\pauli}[1]{\ensuremath{ {\mbf{\sigma}}_{#1} }}

\begin{document}

\section{Introduction}

This is a quick reference for the Measurement and Error Analysis
Library (MEAL).  The classes defined within the {\tt MEAL} namespace
implement a general-purpose library for performing non-linear
least-squares and first-order error propagation.

\section{Function Characteristics}

A mathematical function or expression is characterized by its return
type and input variables; a distinction is made between function
parameters, ${\mbf a}=(a_0, a_1, ... , a_N)$ and independent
variables, or arguments, ${\mbf x}=(x_0, x_1, ... , x_M)$.  Parameters
are double-precision floating point values that can vary freely during
modeling.  Arguments have arbitrary type and cannot be treated as free
variables during modeling.

The parameter and argument access interface is defined by the {\tt
Function} base class, and the return type is defined by {\em
evaluation base classes} that inherit {\tt Function}.  The evaluation
base classes define an {\tt evaluate} method that returns a result,
$f({\mbf x},{\mbf a})$, and the partial derivatives of this result
with respect to each of the parameters, $\partial f/\partial a_i$.

The behaviour of function expression classes is organized into
three categories: Parameter, Argument, and Evaluation.  These
behaviours are implemented by the children of three base classes, 
each of which inherits the {\tt FunctionPolicy} base class.  
The behaviour policies are mutually exclusive, and derived classes can 
incorporate pre-defined behaviours by setting the appropriate 
policy attribute.

\subsection{Parameter Policy}

A function expression may have an arbitary number of scalar parameters,
$\mbf{a}=(a_0, a_1, ... , a_N)$.  Each parameter has an associated
name, estimated variance, and a flag that indicates if the parameter
is free or fixed.  Parameter management and access is implemented by
children of the {\tt ParameterPolicy} base class.

\subsection{Argument Policy}

A function expression may be further parameterized by an arbitrary number
of independent variables, or arguments, ${\mbf x}=(x_0, x_1, ... ,
x_M)$.  Unlike parameters, arguments have no specified type, no
estimated variance, and can never be free.  Because they have no
specified type, the interface between a {\tt Function} and its
arguments is mediated through the {\tt Argument} and {\tt
Argument::Value} abstract base classes.  Argument management and
behaviour is implemented by children of the {\tt ArgumentPolicy} base
class.

\subsection{Evaluation Policy}

The return type of a function expression is unspecified in the 
{\tt Function} base class definition.  Therefore, derived classes must 
inherit an {\em evaluation base class}.  The evaluation base classes are 
children of the {\tt Function} base class that define an {\tt evaluate} method
and an evaluation policy.  There are currently two evaluation base
classes:
\begin{itemize}
\item {\tt Scalar} - returns a scalar (double-precision) value
\item {\tt Complex2} - returns a $2\times2$ complex (double-precision) matrix
\end{itemize}
In addition, a number of template classes, known as {\tt Rules},
implement basic rules of calculus that may be used to simplify the
computation of more complicated expressions and their partial
derivatives.  There are currently two policies for dealing with the
evaluation of a evaluation base-derived class: {\tt Cached} and {\tt
NotCached}.

\section{Modular Construction}

TO DO: Show how new functions can be built up from more basic elements.

\section{Example Usage}

\subsection{Non-linear Least-Squares Estimation}

TO DO: Document lmfit

\subsection{Error Propagation}

The {\tt Estimate} template class is very useful for storing a value
and its estimated variance.  There are also operators and functions
which enable the propagation of error estimates to derived quantities;
for example:
\begin{verbatim}
Estimate<float> y (0.596,0.0034);
Estimate<float> x (-0.83,0.0072);
Estimate<float> z = pow (y,x);
\end{verbatim}
automatically computes the variance of the new variable, {\tt z}.
However, the {\tt Estimate} template class fails when a variable
appears more than once in an expression; e.g.
\begin{verbatim}
Estimate<float> ratio = x/x;
\end{verbatim}
should yield $1\pm0$; however, the {\tt Estimate} template class does
not recognize that the numerator and denominator are the same
variable, and incorrectly sums the weighted variances.

The problem of correctly computing the partial derivatives of an
expression with respect to its variables makes use of the exact same
functionality used to generate the gradient and Hessian matrix in
non-linear least squares fitting.

A simplified interface to this functionality is implemented by the
{\tt ScalarMath} class.  {\tt ScalarMath} objects may be conveniently
initialized as a single parameter and its estimated variance using the
{\tt Estimate} template class.  As with float and double types, {\tt
ScalarMath} objects may be combined using normal arithmetic operations
and basic mathematical functions, creating {\tt Scalar} functions of
any number of parameters.  For example:
\begin{verbatim}
  MEAL::ScalarMath x (Estimate<double> (0.9587, 0.00058));
  MEAL::ScalarMath y (Estimate<double> (-0.283, 0.00034));
  cerr << "Polar angle = " << atan2 (y, x) << endl;
\end{verbatim}
yields the output
\begin{verbatim}
  Polar angle = (-0.287039 +/- 0.0189612)
\end{verbatim}

\noindent
As with any native type, the {\tt ScalarMath} class can be used as a
template argument, e.g.
\begin{verbatim}
  complex<MEAL::ScalarMath> z (Estimate<double> (0.87, 0.0041),
                               Estimate<double> (2.38, 0.0095));

  complex<MEAL::ScalarMath> w (Estimate<double> (1.74, 0.0081),
                               Estimate<double> (-.63, 0.0043));

  Jones<MEAL::ScalarMath> jones (z, conj(z),
                                 conj(w), w);
\end{verbatim}
enabling error propagation through increasingly complex expressions.

\end{document}

  \section model Function Components

  All model components that inherit the MEAL::Function abstract
  base class represent functions of an arbitrary number of variables.
  A distinction is made between independent variables, or arguments,
  \f${\bf x}=(x_0, x_1, ... , x_M)\f$, and model parameters, \f${\bf
  a}=(a_0, a_1, ... , a_N)\f$.  Through use of the
  MEAL::Argument and MEAL::Argument::Value abstract base
  classes, model components may be constrained by one or more
  independent variables of arbitrary type.  The model parameters,
  \f${\bf a}\f$, represent double precision floating point values
  that may need to be constrained by some fitting technique.  Function
  classes should define an evaluation function that returns a result,
  \f$M\f$, and the partial derivative of this result with respect to
  each of the model parameters, \f$\partial M/\partial a_i\f$.  The
  independent variables,\f$\bf x\f$, represent known values, such as
  observing frequency and epoch, that may be used to further constrain
  a model.

  The MEAL::Function class does not define the type of value that
  it represents.  This is defined by derived types, which must define
  a type named Result and a method named evaluate:

  virtual Result evaluate (std::vector<Result>* gradient = 0) const = 0;

  The evaluate method returns a value of the type specified by Result
  and, if a pointer to a vector of Result is passed as the first
  argument, the vector will return the gradient of the return value
  with respect to the model parameters.

  The Return type and evaluate method are implemented by two main
  classes of MEAL::Function derived components:

  <UL> 
  <LI> MEAL::Scalar - a scalar function, 
  \f$f({\bf a}; {\bf x})\f$, such as the MEAL::Polynomial
  <LI> MEAL::Complex2 - a complex 2x2 matrix function,
  \f$J({\bf a}; {\bf x})\f$, such as the MEAL::Coherency matrix 
  and the MEAL::Rotation transformation.
  </UL>


  \subsection calculus Partial Derivatives

  A number of template classes may be used to simplify the modular
  construction of more complicated functions.  These templates
  implement the following basic rules of differentiation:

  <UL> 

  <LI> MEAL::ChainRule - an arbitrary function in which
  one or more parameters is set equal to the ordinate of a 
  MEAL::Scalar function

  <LI> MEAL::BinaryRule - an associative binary operation, such
  as the sum (MEAL::SumRule) or product
  (MEAL::ProductRule).

  </UL>
